-- card: 5605 from stack: in
-- bmap block id: 0
-- flags: 4000
-- background id: 3503
-- name: About Hyper-GunShy
----- HyperTalk script -----
-- Documentation on the Hyper-GunShy Stack
-- T. R. Teague - 6 Sep 87
-- For answers to your questions, contact me on CompuServe 76354,324
--
-- This is my first HyperCard Stack, and I thought I would share with
-- you, some of the experience I gained in doing this stack.
--
-- I had played with HyperCard a little, using the tutorial stacks
-- (although I didn't have any documentation at this stage).
-- The idea came to me, from seeing that GunShy looked like a whole
-- series of buttons with icons on them - 2 major parts of HyperCard.
--
-- The first thing I did was create about 100 buttons of approx. the
-- right size, with a single standard icon on them. This gave me a feel
-- for authoring a stack (that was easy). Then I experimented with the
-- button layers (not understanding them at the time) but thought that
-- they might be useful to hide layers as per GunShy. Then I created
-- the Home, About, Help, Return buttons, and copied the scripts from
-- other stacks, and tested them out.
--
-- At this stage, I needed to customize the stack - so I imported a
-- PICT resource and all the ICON & ICN# resources from GunShy with
-- the use of ResEdit, and pasted them into the background and stack
-- respectively - that was simple, and made a major impact on the
-- stack.
--
-- This was when I started thinking about the logic of the game.
-- I had spent a lot of time to this point going back and forth to the
-- on-line help, and this gave me a feel for the power of HyperCard,
-- but I wished to have the on-line help visible at all times,
-- especially when editing a script.
--
-- I created the other cards for the stack, such as About, Help, and
-- entered the relevant info - the help fields were easy (but took me
-- a while to figure out how to see where I had to type etc), but I
-- had forgotten how the Text Paint Tool worked, so it took several
-- attempts to get the About card right (I wanted to have different
-- fonts/styles etc as part of the About message, but couldn't).
--
-- By this time I had figured out that I didn't want to duplicate the
-- code for every button on the first card, and understood the power
-- of message handlers and inheritance - so I decided to put the main
-- code on that first card. Also I had also put the GunShy menus into
-- buttons on this card. But as I started writing code and testing it,
-- it was obvious that these buttons might interfere with the icon
-- buttons, so this is when I started experimenting with putting
-- different functional parts on cards, and others on backgrounds -
-- that turned out ok.
--
-- It was probably at this stage that I obtained documentation - the
-- Complete HyperCard HandBook by Danny Goodman and read it. Most of
-- it I had figured out by now, but learnt a few things like layers
-- and how the Tools/Paint/Option menus performed. It would help with
-- HyperTalk syntax. Also I kept getting hold of as many third-party
-- stacks as I could, to learn what they had done, and I borrowed a
-- few ideas. I had some problems moving cards and backgrounds around -
-- the limitation of when you copy a card, the background comes with it
-- automatically was annoying. An option type key would have been useful.
--
-- It was time for serious programming. Some of it went simply at first
-- so that the basic selection, highlighting, and hiding of icon buttons
-- occurred, and appropriate values were put into variables. I learnt
-- a lot about Global variables, and items, words, and containers.
-- My If/Then/Else/End If logic was getting more complicated and I
-- appreciated the power of Scripting, such that Begin/End's were
-- matched up for me. Also at this stage, the Message Box came in very
-- handy to debug variables - I set some of my local variables to global
-- just so I could debug it from the Msg Box directly - otherwise I
-- liberally sprinkled the script with Put messages to see what was
-- happening. I found the interpretative nature of HyperTalk a big boon
-- as I was able to abort scripts when they didn't work, make some
-- changes, and then continue with the code, and when I had made a
-- syntax error in the changes, correct it immediately.
--
-- Some the limitations of HyperTalk became apparent - it is too slow
-- for some things, and several times I had to think about ways to make
-- the program more efficient, and introduced more variables. I also
-- had a worry about how big a string a container could hold, as my
-- strings were getting quite long, and some things weren't working
-- right - as it turned out, I had run into a HyperCard bug - it does
-- not seem to be able to handle complex expressions, and was doing
-- screwy things to my variables. I had to make quite a number of
-- adjustments to work around these problems, and I began to wonder
-- what other problems were lurking.
--
-- I found one limitation that I needed to address - when choosing
-- icons randomly for buttons, HyperCard was not smart enough to tell
-- me if a particular icon was available or not - I decided this was
-- a good candidate for an external HyperCard cmd (XCMD or XFCN).
-- I had seen the WildSwaps & WildHacks stacks and external commands
-- and had a good idea of how it worked. But I got the documentation
-- for external commands, and that added something to my learning.
-- The code was easy to write, but a simple mistake on my part stopped
-- it from working initally, but after that was fixed, it worked first
-- time. The source code may be included below.
--
-- Now it was time for the nitty gritty work of debugging the code
-- and adding the actual game logic (the rules of the game - see
-- LegalMove handler), which I had left to last after the rest of the
-- mechanics seemed to be working. I did run into a few other problems
-- in which use of user defined functions and commands did not interact
-- exactly with HyperTalk as the documentation led me to believe. I
-- think most of the grief was caused by the the HyperTalk bugs and
-- difficulty in manipulating items in a list of numbers in a container.
--
-- Finally it was clean-up time, and final testing.
--
-
-- One trick I learnt : if you have a command such as :
--
-- send "newstuff" to this card
--
-- and your debugging clears the msg box, and you need to enter that
-- command often (to fix up "corrupted" data), you get tired of typing
-- that long command in every time. So at some time enter the following
-- into the msg box :
--
-- put "send "&quote&"newstuff"&quote&" to this card" into savecmd
--
-- to use the command, just enter thereafter into the msg box :
--
-- savecmd
--
--
-- Conclusions : what did I learn - HyperCard is a very powerful tool,
-- but has some limitations (mainly one of speed) to be aware of.
-- The program could be made more efficient, by having more variables
-- which hold information, which doesn't have to be calculated all the
-- time (e.g. compare speed of Option Key handler while doing the
-- work, and the speed of the same handler when cleaning up)
-- There are probably still some bugs - there seems to be one in the
-- Open/Save scripts - an extra blank card seems to be produced in some
-- circumstances.
--
-- External function follows :
--

{$R-}

{$S GetIcon } 	{ Segment name must be the same as the command name. }

UNIT DummyUnit;

INTERFACE

USES MemTypes, HyperXCmd, QuickDraw, OSIntf, ToolIntf;

PROCEDURE EntryPoint(paramPtr: XCmdPtr);

IMPLEMENTATION

TYPE Str31 = String[31];
Str19 = String[19];
WordPtr = ^INTEGER;
LongPtr = ^LongInt;

PROCEDURE MyGetIcon(paramPtr: XCmdPtr); FORWARD;

PROCEDURE EntryPoint(paramPtr: XCmdPtr);
BEGIN
MyGetIcon(paramPtr);
END;

PROCEDURE MyGetIcon(paramPtr: XCmdPtr);
VAR str: Str255;
IconNum : integer;
MyHandle : Handle;
gotIcon : boolean;

{$I XCmdGlue.inc }

BEGIN
WITH paramPtr^ DO
BEGIN
{ first param is ICN# }
ZeroToPas(params[1]^,str);
IconNum := StrToNum(str);

gotIcon := false;

MyHandle := GetResource('ICON',IconNum);
if (MyHandle = nil) then
  begin
  MyHandle := GetResource('ICN#',IconNum);
  end;

  if (MyHandle <> nil) then
    begin
    gotIcon := true;
    ReleaseResource(MyHandle);
    end;

    str := BoolToStr(gotIcon);
    returnValue := PasToZero(str);
    END;
    END;


    END.


    --
    -- Have fun!




-- part 1 (button)
-- low flags: 00
-- high flags: 0000
-- rect: left=466 top=316 right=341 bottom=503
-- title width / last selected line: 0
-- icon id / first selected line: 1012 / 1012
-- text alignment: 1
-- font id: 0
-- text size: 12
-- style flags: 0
-- line height: 16
-- part name: 
----- HyperTalk script -----
on mouseUp
  visual effect iris close
  pop card
end mouseUp



-- part contents for background part 2
----- text -----
Paste this button into your Home Stack.